Hi @YanisaHS, could you please review this PR with me? I would appreciate some opinions on the clarity and structure of the document.

@MichaelThamm Yea, I'd be happy to! 😊 I likely won't have time to review it until Tuesday though (I'm off Monday)

@MichaelThamm Yea, I'd be happy to! 😊 I likely won't have time to review it until Tuesday though (I'm off Monday)

@YanisaHS This PR is still a work in progress. It may be best to wait until I make some more progress before reviewing this PR. The docs still need updating before first review.

@MichaelThamm Ok, sounds good! Just tag me when you're ready again

@YanisaHS

I think it is ready for review now: docs link

Some input I would like from you is:

• This feature (updating channel updates charms to latest revision) is not guaranteed to work across tracks. In the tutorial, it shows 2/stable to 2/edge which is within the same track so it should be guaranteed to work.
• Would you convert this into a How-to instead of a tutorial?

I need to add a comment to the doc about not guaranteed to work across tracks.

@MichaelThamm Ok! I'll review it soon (was off the end of last week)

@MichaelThamm I'll go through and actually provide feedback in the doc, but first addressing your two issues:

This feature (updating channel updates charms to latest revision) is not guaranteed to work across tracks. In the tutorial, it shows 2/stable to 2/edge which is within the same track so it should be guaranteed to work.

For a tutorial, this is fine. I'd still recommend you add a note (as you suggested) describing this condition, mostly for any driveby users / people who find this without realizing they're in a Diataxis ✨ tutorial ✨. Tutorials are more of a "sandboxed" experience, so it's okay to feed the user the configurations they need.

But...

Would you convert this into a How-to instead of a tutorial?

Yes. The Tutorials section in the Observability docs gives the docs in order a new user should follow, so now it reads like (1) Deploy, (2) Refresh, (3) Sync .. etc. The experience feels odd for a new user - if it's important they're on this track, then that should be given to them in the previous Deploy steps, rather than deploying and refreshing right after.

Actually this is something we'll discuss as a team this cycle: From a user's perspective, one of the most immediate concerns I have with the docs is that they don't clearly state how to deploy COS in the How-to guides (examples: Charmed Kafka, Charmed Postgres, Charmed K8s). When this is the first thing a user needs to do to access the product (and rest of the documentation).

I'll provide feedback with this in mind as I go through your PR - assuming you'll refactor it into a how-to guide.

When trying to upgrade, I was getting this output:

module.cos-lite.module.grafana.juju_application.grafana: Modifications complete after 2s  ← provider returned, Juju still refreshing
module.cos-lite.juju_integration.grafana_ingress[0]: Creating...                          ← immediately tries new endpoint
│ Error: no relations found                                                                ← old charm still active

Summarizing my call with @adhityaravi:

1. We can try to backport (into an ephemeral branch off of track/2) the terraform_data for the juju_charm.resources and/or juju_charm.requires["ingress"] for both COS Lite and Grafana TF modules and reference those in the itest and retry to test that the lifecycle action actually takes place.
2. resource "juju_integration" "grafana_ingress" -> Unable to create integration, got error: no relations found
   • is this a timing issue with Terraform bc Grafana actually becomes dev/edge, but is in Error state. I was able to manually relate Grafana:ingress to Traefik:ingress, which indicates this could be a timing issue.

Testing COS Lite from track/2 -> dev/edge

terraform {
  required_version = ">= 1.5"
  required_providers {
    juju = {
      source  = "juju/juju"
      version = "~> 1.0"
    }
  }
}

resource "juju_model" "cos-lite" {
  name = "cos-lite"
}

module "cos-lite" {
  source = "git::https://github.com/canonical/observability-stack//terraform/cos-lite?ref=track/2"
  channel      = "2/stable"
  model_uuid   = juju_model.cos-lite.uuid
  internal_tls = false
}

❯ tf init
❯ tf apply
Apply complete! Resources: 32 added, 0 changed, 0 destroyed.

then update the module and apply:

module "cos-lite" {
  source = "git::https://github.com/canonical/observability-stack//terraform/cos-lite?ref=test/tf-lifecycle"
  channel      = "2/stable"
  model_uuid   = juju_model.cos-lite.uuid
  internal_tls = false
}

❯ tf init -upgrade
❯ tf apply
Terraform will perform the following actions:

  # module.cos-lite.terraform_data.grafana_ingress_interface will be created
  + resource "terraform_data" "grafana_ingress_interface" {
      + id               = (known after apply)
      + triggers_replace = "traefik_route"
    }

  # module.cos-lite.terraform_data.grafana_litestream_resource will be created
  + resource "terraform_data" "grafana_litestream_resource" {
      + id               = (known after apply)
      + triggers_replace = true
    }

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

then update the module & risk and apply:

module "cos-lite" {
  source       = "../../terraform/cos-lite"
  risk         = "edge"
  model_uuid   = juju_model.cos-lite.uuid
  internal_tls = false
}

❯ tf init -upgrade
❯ tf apply
Terraform will perform the following actions:

  # module.cos-lite.juju_integration.grafana_ingress[0] will be replaced due to changes in replace_triggered_by
  # (moved from module.cos-lite.juju_integration.grafana_ingress)
-/+ resource "juju_integration" "grafana_ingress" {
      ~ id         = "335d5e05-3b09-493c-8c30-d73fa780f21b:traefik:traefik-route:grafana:ingress" -> (known after apply)
        # (1 unchanged attribute hidden)

      - application { # forces replacement
          - endpoint = "traefik-route" -> null
          - name     = "traefik" -> null
        }
      + application { # forces replacement
          + endpoint = "ingress"
          + name     = "traefik"
        }

        # (1 unchanged block hidden)
    }

  # module.cos-lite.terraform_data.grafana_ingress_interface must be replaced
-/+ resource "terraform_data" "grafana_ingress_interface" {
      ~ id               = "ea3af7ce-9e26-5975-e091-a756d7835a08" -> (known after apply)
      ~ triggers_replace = "traefik_route" -> "ingress"
    }

  # module.cos-lite.module.grafana.juju_application.grafana will be replaced due to changes in replace_triggered_by
-/+ resource "juju_application" "grafana" {
      ~ id                 = "335d5e05-3b09-493c-8c30-d73fa780f21b:grafana" -> (known after apply)
      ~ machines           = [] -> (known after apply)
      ~ model_type         = "caas" -> (known after apply)
        name               = "grafana"
      ~ storage            = [
          - {
              - count = 1 -> null
              - label = "database" -> null
              - pool  = "kubernetes" -> null
              - size  = "1G" -> null
            },
        ] -> (known after apply)
        # (6 unchanged attributes hidden)

      ~ charm {
          ~ base     = "ubuntu@24.04" -> (known after apply)
          ~ channel  = "2/stable" -> "dev/edge"
            name     = "grafana-k8s"
          ~ revision = 180 -> 186
        }
    }

  # module.cos-lite.module.grafana.terraform_data.grafana_litestream_resource must be replaced
-/+ resource "terraform_data" "grafana_litestream_resource" {
      ~ id               = "b26c2ad5-4ee2-4a37-cf7d-85fd10ce77b4" -> (known after apply)
      ~ triggers_replace = true -> false
    }

Plan: 9 to add, 6 to change, 8 to destroy.

Apply complete! Resources: 8 added, 5 changed, 8 destroyed.

terraform state rm 'module.cos-lite.juju_offer.grafana_dashboards'
Removed module.cos-lite.juju_offer.grafana_dashboards
Successfully removed 1 resource instance(s).

terraform apply
Apply complete! Resources: 9 added, 0 changed, 0 destroyed.

tf apply